<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head><title>Python: class StoppableThread</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head><body bgcolor="#f0f0f8">
<p>
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
<tr bgcolor="#ffc8d8">
<td colspan=3 valign=bottom>&nbsp;<br>
<font color="#000000" face="helvetica, arial"><strong>func_timeout.StoppableThread</strong> = <a name="func_timeout.StoppableThread">class StoppableThread</a>(<a href="threading.html#Thread">threading.Thread</a>)</font></td></tr>
    
<tr bgcolor="#ffc8d8"><td rowspan=2><tt>&nbsp;&nbsp;&nbsp;</tt></td>
<td colspan=2><tt>func_timeout.StoppableThread(group=None,&nbsp;target=None,&nbsp;name=None,&nbsp;args=(),&nbsp;kwargs=None,&nbsp;*,&nbsp;daemon=None)<br>
&nbsp;<br>
StoppableThread&nbsp;-&nbsp;A&nbsp;thread&nbsp;that&nbsp;can&nbsp;be&nbsp;stopped&nbsp;by&nbsp;forcing&nbsp;an&nbsp;exception&nbsp;in&nbsp;the&nbsp;execution&nbsp;context.<br>
&nbsp;<br>
&nbsp;&nbsp;This&nbsp;works&nbsp;both&nbsp;to&nbsp;interrupt&nbsp;code&nbsp;that&nbsp;is&nbsp;in&nbsp;C&nbsp;or&nbsp;in&nbsp;python&nbsp;code,&nbsp;at&nbsp;either&nbsp;the&nbsp;next&nbsp;call&nbsp;to&nbsp;a&nbsp;python&nbsp;function,<br>
&nbsp;&nbsp;&nbsp;or&nbsp;the&nbsp;next&nbsp;line&nbsp;in&nbsp;python&nbsp;code.<br>
&nbsp;<br>
It&nbsp;is&nbsp;recommended&nbsp;that&nbsp;if&nbsp;you&nbsp;call&nbsp;stop&nbsp;(&nbsp;@see&nbsp;StoppableThread.stop&nbsp;)&nbsp;that&nbsp;you&nbsp;use&nbsp;an&nbsp;exception&nbsp;that&nbsp;inherits&nbsp;BaseException,&nbsp;to&nbsp;ensure&nbsp;it&nbsp;likely&nbsp;isn't&nbsp;caught.<br>
&nbsp;<br>
&nbsp;Also,&nbsp;beware&nbsp;unmarked&nbsp;exception&nbsp;handlers&nbsp;in&nbsp;your&nbsp;code.&nbsp;Code&nbsp;like&nbsp;this:<br>
&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;while&nbsp;True:<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;try:<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;doSomething()<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;except:<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;continue<br>
&nbsp;<br>
will&nbsp;never&nbsp;be&nbsp;able&nbsp;to&nbsp;abort,&nbsp;because&nbsp;the&nbsp;exception&nbsp;you&nbsp;raise&nbsp;is&nbsp;immediately&nbsp;caught.<br>
&nbsp;<br>
The&nbsp;exception&nbsp;is&nbsp;raised&nbsp;over&nbsp;and&nbsp;over,&nbsp;with&nbsp;a&nbsp;specifed&nbsp;delay&nbsp;(default&nbsp;2.0&nbsp;seconds)<br>&nbsp;</tt></td></tr>
<tr><td>&nbsp;</td>
<td width="100%"><dl><dt>Method resolution order:</dt>
<dd><a href="func_timeout.StoppableThread.html#StoppableThread">StoppableThread</a></dd>
<dd><a href="threading.html#Thread">threading.Thread</a></dd>
<dd><a href="builtins.html#object">builtins.object</a></dd>
</dl>
<hr>
Methods defined here:<br>
<dl><dt><a name="StoppableThread-stop"><strong>stop</strong></a>(self, exception, raiseEvery=2.0)</dt><dd><tt>Stops&nbsp;the&nbsp;thread&nbsp;by&nbsp;raising&nbsp;a&nbsp;given&nbsp;exception.<br>
&nbsp;<br>
@param&nbsp;exception&nbsp;&lt;Exception&nbsp;type&gt;&nbsp;-&nbsp;Exception&nbsp;to&nbsp;throw.&nbsp;Likely,&nbsp;you&nbsp;want&nbsp;to&nbsp;use&nbsp;something<br>
&nbsp;<br>
&nbsp;&nbsp;that&nbsp;inherits&nbsp;from&nbsp;BaseException&nbsp;(so&nbsp;except&nbsp;Exception&nbsp;as&nbsp;e:&nbsp;continue;&nbsp;isn't&nbsp;a&nbsp;problem)<br>
&nbsp;<br>
&nbsp;&nbsp;This&nbsp;should&nbsp;be&nbsp;a&nbsp;class/type,&nbsp;NOT&nbsp;an&nbsp;instance,&nbsp;i.e.&nbsp;&nbsp;MyExceptionType&nbsp;&nbsp;&nbsp;not&nbsp;&nbsp;MyExceptionType()<br>
&nbsp;<br>
&nbsp;<br>
@param&nbsp;raiseEvery&nbsp;&lt;float&gt;&nbsp;Default&nbsp;2.0&nbsp;-&nbsp;We&nbsp;will&nbsp;keep&nbsp;raising&nbsp;this&nbsp;exception&nbsp;every&nbsp;#raiseEvery&nbsp;seconds,<br>
&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;until&nbsp;the&nbsp;thread&nbsp;terminates.<br>
&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;If&nbsp;your&nbsp;code&nbsp;traps&nbsp;a&nbsp;specific&nbsp;exception&nbsp;type,&nbsp;this&nbsp;will&nbsp;allow&nbsp;you&nbsp;#raiseEvery&nbsp;seconds&nbsp;to&nbsp;cleanup&nbsp;before&nbsp;exit.<br>
&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;If&nbsp;you're&nbsp;calling&nbsp;third-party&nbsp;code&nbsp;you&nbsp;can't&nbsp;control,&nbsp;which&nbsp;catches&nbsp;BaseException,&nbsp;set&nbsp;this&nbsp;to&nbsp;a&nbsp;low&nbsp;number<br>
&nbsp;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;to&nbsp;break&nbsp;out&nbsp;of&nbsp;their&nbsp;exception&nbsp;handler.<br>
&nbsp;<br>
&nbsp;<br>
&nbsp;@return&nbsp;&lt;None&gt;</tt></dd></dl>

<hr>
Methods inherited from <a href="threading.html#Thread">threading.Thread</a>:<br>
<dl><dt><a name="StoppableThread-__init__"><strong>__init__</strong></a>(self, group=None, target=None, name=None, args=(), kwargs=None, *, daemon=None)</dt><dd><tt>This&nbsp;constructor&nbsp;should&nbsp;always&nbsp;be&nbsp;called&nbsp;with&nbsp;keyword&nbsp;arguments.&nbsp;Arguments&nbsp;are:<br>
&nbsp;<br>
*group*&nbsp;should&nbsp;be&nbsp;None;&nbsp;reserved&nbsp;for&nbsp;future&nbsp;extension&nbsp;when&nbsp;a&nbsp;ThreadGroup<br>
class&nbsp;is&nbsp;implemented.<br>
&nbsp;<br>
*target*&nbsp;is&nbsp;the&nbsp;callable&nbsp;object&nbsp;to&nbsp;be&nbsp;invoked&nbsp;by&nbsp;the&nbsp;<a href="#func_timeout.StoppableThread-run">run</a>()<br>
method.&nbsp;Defaults&nbsp;to&nbsp;None,&nbsp;meaning&nbsp;nothing&nbsp;is&nbsp;called.<br>
&nbsp;<br>
*name*&nbsp;is&nbsp;the&nbsp;thread&nbsp;name.&nbsp;By&nbsp;default,&nbsp;a&nbsp;unique&nbsp;name&nbsp;is&nbsp;constructed&nbsp;of<br>
the&nbsp;form&nbsp;"Thread-N"&nbsp;where&nbsp;N&nbsp;is&nbsp;a&nbsp;small&nbsp;decimal&nbsp;number.<br>
&nbsp;<br>
*args*&nbsp;is&nbsp;the&nbsp;argument&nbsp;tuple&nbsp;for&nbsp;the&nbsp;target&nbsp;invocation.&nbsp;Defaults&nbsp;to&nbsp;().<br>
&nbsp;<br>
*kwargs*&nbsp;is&nbsp;a&nbsp;dictionary&nbsp;of&nbsp;keyword&nbsp;arguments&nbsp;for&nbsp;the&nbsp;target<br>
invocation.&nbsp;Defaults&nbsp;to&nbsp;{}.<br>
&nbsp;<br>
If&nbsp;a&nbsp;subclass&nbsp;overrides&nbsp;the&nbsp;constructor,&nbsp;it&nbsp;must&nbsp;make&nbsp;sure&nbsp;to&nbsp;invoke<br>
the&nbsp;base&nbsp;class&nbsp;constructor&nbsp;(Thread.<a href="#func_timeout.StoppableThread-__init__">__init__</a>())&nbsp;before&nbsp;doing&nbsp;anything<br>
else&nbsp;to&nbsp;the&nbsp;thread.</tt></dd></dl>

<dl><dt><a name="StoppableThread-__repr__"><strong>__repr__</strong></a>(self)</dt><dd><tt>Return&nbsp;repr(self).</tt></dd></dl>

<dl><dt><a name="StoppableThread-getName"><strong>getName</strong></a>(self)</dt></dl>

<dl><dt><a name="StoppableThread-isAlive"><strong>isAlive</strong></a>(self)</dt><dd><tt>Return&nbsp;whether&nbsp;the&nbsp;thread&nbsp;is&nbsp;alive.<br>
&nbsp;<br>
This&nbsp;method&nbsp;is&nbsp;deprecated,&nbsp;use&nbsp;<a href="#func_timeout.StoppableThread-is_alive">is_alive</a>()&nbsp;instead.</tt></dd></dl>

<dl><dt><a name="StoppableThread-isDaemon"><strong>isDaemon</strong></a>(self)</dt></dl>

<dl><dt><a name="StoppableThread-is_alive"><strong>is_alive</strong></a>(self)</dt><dd><tt>Return&nbsp;whether&nbsp;the&nbsp;thread&nbsp;is&nbsp;alive.<br>
&nbsp;<br>
This&nbsp;method&nbsp;returns&nbsp;True&nbsp;just&nbsp;before&nbsp;the&nbsp;<a href="#func_timeout.StoppableThread-run">run</a>()&nbsp;method&nbsp;starts&nbsp;until&nbsp;just<br>
after&nbsp;the&nbsp;<a href="#func_timeout.StoppableThread-run">run</a>()&nbsp;method&nbsp;terminates.&nbsp;The&nbsp;module&nbsp;function&nbsp;enumerate()<br>
returns&nbsp;a&nbsp;list&nbsp;of&nbsp;all&nbsp;alive&nbsp;threads.</tt></dd></dl>

<dl><dt><a name="StoppableThread-join"><strong>join</strong></a>(self, timeout=None)</dt><dd><tt>Wait&nbsp;until&nbsp;the&nbsp;thread&nbsp;terminates.<br>
&nbsp;<br>
This&nbsp;blocks&nbsp;the&nbsp;calling&nbsp;thread&nbsp;until&nbsp;the&nbsp;thread&nbsp;whose&nbsp;<a href="#func_timeout.StoppableThread-join">join</a>()&nbsp;method&nbsp;is<br>
called&nbsp;terminates&nbsp;--&nbsp;either&nbsp;normally&nbsp;or&nbsp;through&nbsp;an&nbsp;unhandled&nbsp;exception<br>
or&nbsp;until&nbsp;the&nbsp;optional&nbsp;timeout&nbsp;occurs.<br>
&nbsp;<br>
When&nbsp;the&nbsp;timeout&nbsp;argument&nbsp;is&nbsp;present&nbsp;and&nbsp;not&nbsp;None,&nbsp;it&nbsp;should&nbsp;be&nbsp;a<br>
floating&nbsp;point&nbsp;number&nbsp;specifying&nbsp;a&nbsp;timeout&nbsp;for&nbsp;the&nbsp;operation&nbsp;in&nbsp;seconds<br>
(or&nbsp;fractions&nbsp;thereof).&nbsp;As&nbsp;<a href="#func_timeout.StoppableThread-join">join</a>()&nbsp;always&nbsp;returns&nbsp;None,&nbsp;you&nbsp;must&nbsp;call<br>
<a href="#func_timeout.StoppableThread-is_alive">is_alive</a>()&nbsp;after&nbsp;<a href="#func_timeout.StoppableThread-join">join</a>()&nbsp;to&nbsp;decide&nbsp;whether&nbsp;a&nbsp;timeout&nbsp;happened&nbsp;--&nbsp;if&nbsp;the<br>
thread&nbsp;is&nbsp;still&nbsp;alive,&nbsp;the&nbsp;<a href="#func_timeout.StoppableThread-join">join</a>()&nbsp;call&nbsp;timed&nbsp;out.<br>
&nbsp;<br>
When&nbsp;the&nbsp;timeout&nbsp;argument&nbsp;is&nbsp;not&nbsp;present&nbsp;or&nbsp;None,&nbsp;the&nbsp;operation&nbsp;will<br>
block&nbsp;until&nbsp;the&nbsp;thread&nbsp;terminates.<br>
&nbsp;<br>
A&nbsp;thread&nbsp;can&nbsp;be&nbsp;<a href="#func_timeout.StoppableThread-join">join</a>()ed&nbsp;many&nbsp;times.<br>
&nbsp;<br>
<a href="#func_timeout.StoppableThread-join">join</a>()&nbsp;raises&nbsp;a&nbsp;RuntimeError&nbsp;if&nbsp;an&nbsp;attempt&nbsp;is&nbsp;made&nbsp;to&nbsp;join&nbsp;the&nbsp;current<br>
thread&nbsp;as&nbsp;that&nbsp;would&nbsp;cause&nbsp;a&nbsp;deadlock.&nbsp;It&nbsp;is&nbsp;also&nbsp;an&nbsp;error&nbsp;to&nbsp;<a href="#func_timeout.StoppableThread-join">join</a>()&nbsp;a<br>
thread&nbsp;before&nbsp;it&nbsp;has&nbsp;been&nbsp;started&nbsp;and&nbsp;attempts&nbsp;to&nbsp;do&nbsp;so&nbsp;raises&nbsp;the&nbsp;same<br>
exception.</tt></dd></dl>

<dl><dt><a name="StoppableThread-run"><strong>run</strong></a>(self)</dt><dd><tt>Method&nbsp;representing&nbsp;the&nbsp;thread's&nbsp;activity.<br>
&nbsp;<br>
You&nbsp;may&nbsp;override&nbsp;this&nbsp;method&nbsp;in&nbsp;a&nbsp;subclass.&nbsp;The&nbsp;standard&nbsp;<a href="#func_timeout.StoppableThread-run">run</a>()&nbsp;method<br>
invokes&nbsp;the&nbsp;callable&nbsp;object&nbsp;passed&nbsp;to&nbsp;the&nbsp;object's&nbsp;constructor&nbsp;as&nbsp;the<br>
target&nbsp;argument,&nbsp;if&nbsp;any,&nbsp;with&nbsp;sequential&nbsp;and&nbsp;keyword&nbsp;arguments&nbsp;taken<br>
from&nbsp;the&nbsp;args&nbsp;and&nbsp;kwargs&nbsp;arguments,&nbsp;respectively.</tt></dd></dl>

<dl><dt><a name="StoppableThread-setDaemon"><strong>setDaemon</strong></a>(self, daemonic)</dt></dl>

<dl><dt><a name="StoppableThread-setName"><strong>setName</strong></a>(self, name)</dt></dl>

<dl><dt><a name="StoppableThread-start"><strong>start</strong></a>(self)</dt><dd><tt>Start&nbsp;the&nbsp;thread's&nbsp;activity.<br>
&nbsp;<br>
It&nbsp;must&nbsp;be&nbsp;called&nbsp;at&nbsp;most&nbsp;once&nbsp;per&nbsp;thread&nbsp;object.&nbsp;It&nbsp;arranges&nbsp;for&nbsp;the<br>
object's&nbsp;<a href="#func_timeout.StoppableThread-run">run</a>()&nbsp;method&nbsp;to&nbsp;be&nbsp;invoked&nbsp;in&nbsp;a&nbsp;separate&nbsp;thread&nbsp;of&nbsp;control.<br>
&nbsp;<br>
This&nbsp;method&nbsp;will&nbsp;raise&nbsp;a&nbsp;RuntimeError&nbsp;if&nbsp;called&nbsp;more&nbsp;than&nbsp;once&nbsp;on&nbsp;the<br>
same&nbsp;thread&nbsp;object.</tt></dd></dl>

<hr>
Data descriptors inherited from <a href="threading.html#Thread">threading.Thread</a>:<br>
<dl><dt><strong>__dict__</strong></dt>
<dd><tt>dictionary&nbsp;for&nbsp;instance&nbsp;variables&nbsp;(if&nbsp;defined)</tt></dd>
</dl>
<dl><dt><strong>__weakref__</strong></dt>
<dd><tt>list&nbsp;of&nbsp;weak&nbsp;references&nbsp;to&nbsp;the&nbsp;object&nbsp;(if&nbsp;defined)</tt></dd>
</dl>
<dl><dt><strong>daemon</strong></dt>
<dd><tt>A&nbsp;boolean&nbsp;value&nbsp;indicating&nbsp;whether&nbsp;this&nbsp;thread&nbsp;is&nbsp;a&nbsp;daemon&nbsp;thread.<br>
&nbsp;<br>
This&nbsp;must&nbsp;be&nbsp;set&nbsp;before&nbsp;start()&nbsp;is&nbsp;called,&nbsp;otherwise&nbsp;RuntimeError&nbsp;is<br>
raised.&nbsp;Its&nbsp;initial&nbsp;value&nbsp;is&nbsp;inherited&nbsp;from&nbsp;the&nbsp;creating&nbsp;thread;&nbsp;the<br>
main&nbsp;thread&nbsp;is&nbsp;not&nbsp;a&nbsp;daemon&nbsp;thread&nbsp;and&nbsp;therefore&nbsp;all&nbsp;threads&nbsp;created&nbsp;in<br>
the&nbsp;main&nbsp;thread&nbsp;default&nbsp;to&nbsp;daemon&nbsp;=&nbsp;False.<br>
&nbsp;<br>
The&nbsp;entire&nbsp;Python&nbsp;program&nbsp;exits&nbsp;when&nbsp;no&nbsp;alive&nbsp;non-daemon&nbsp;threads&nbsp;are<br>
left.</tt></dd>
</dl>
<dl><dt><strong>ident</strong></dt>
<dd><tt>Thread&nbsp;identifier&nbsp;of&nbsp;this&nbsp;thread&nbsp;or&nbsp;None&nbsp;if&nbsp;it&nbsp;has&nbsp;not&nbsp;been&nbsp;started.<br>
&nbsp;<br>
This&nbsp;is&nbsp;a&nbsp;nonzero&nbsp;integer.&nbsp;See&nbsp;the&nbsp;get_ident()&nbsp;function.&nbsp;Thread<br>
identifiers&nbsp;may&nbsp;be&nbsp;recycled&nbsp;when&nbsp;a&nbsp;thread&nbsp;exits&nbsp;and&nbsp;another&nbsp;thread&nbsp;is<br>
created.&nbsp;The&nbsp;identifier&nbsp;is&nbsp;available&nbsp;even&nbsp;after&nbsp;the&nbsp;thread&nbsp;has&nbsp;exited.</tt></dd>
</dl>
<dl><dt><strong>name</strong></dt>
<dd><tt>A&nbsp;string&nbsp;used&nbsp;for&nbsp;identification&nbsp;purposes&nbsp;only.<br>
&nbsp;<br>
It&nbsp;has&nbsp;no&nbsp;semantics.&nbsp;Multiple&nbsp;threads&nbsp;may&nbsp;be&nbsp;given&nbsp;the&nbsp;same&nbsp;name.&nbsp;The<br>
initial&nbsp;name&nbsp;is&nbsp;set&nbsp;by&nbsp;the&nbsp;constructor.</tt></dd>
</dl>
</td></tr></table>
</body></html>